home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 May: Tool Chest / Developer CD Series Tool Chest (Apple Computer)(May 1999).iso / Tool Chest / Communications Toolbox / CTB Development Resources / CTB API Overview next >
Encoding:
Text File  |  1992-05-13  |  3.9 KB  |  85 lines  |  [TEXT/MPS ]
  1.                                                             Author
  2.                                                             ------
  3.                                                             Craig Hotchkiss
  4.  
  5. The Communications Toolbox API
  6. ==============================
  7. Okay, first the standard paragraph:
  8.  
  9. Traditional communications applications provide access to terminal emulations, file
  10. transfer services, and connection services.  The CommToolbox Application Programming
  11. Interface provides consistency for accessing these services, both from the application
  12. and tool points of view.
  13.  
  14. What this really means:
  15.  
  16. If you follow this interface closely your tool or application will work in a wide 
  17. variety of environments.  This allows for great sales opportunities.
  18.  
  19. What it DOESN'T mean:
  20.  
  21. Tools/applications providing similar services need to operate and perform 
  22. similarly (NOT!).  
  23.  
  24.  
  25. It is true that by following this interface tool or application response is similar 
  26. but the methods used to get the job done can be radically different.  For example, 
  27. imagine a modem tool with address book capabilities for frequently called numbers or
  28. a tool that provides a language popup menu to switch dialog item text between languages.
  29.  
  30.  
  31.  
  32. Application conformance tips
  33. ----------------------------
  34. You can save yourself some debugging time by using the user interface to protect the
  35. user and your application from causing difficulties.  For example, disable any 'Open
  36. Connection' menu item after CMOpen so that the user cannot select it again.  Then use
  37. CMStatus to determine if the menu item can be reenabled.  
  38.  
  39. If you have any doubt about appropriate behavior you may not have all the information
  40. you need.  It is sometimes helpful to also understand how the tool is supposed to 
  41. behave so don't stop reading after the manager chapters of Inside Mac CTB, also look
  42. for the corresponding message that gets sent to the tool and read the tool chapters.
  43.  
  44. If you are still unclear, use the CommToolbox Talk folder on AppleLink to discuss
  45. the problem.  Everybody has opinions and even though an Apple engineer may not
  46. be available to respond, they will probably read it and thus be aware of the unclear
  47. nature of the API or documentation.  CommToolbox was/is a big project and there 
  48. will probably always be some shake-out in progress because of the wide variety of 
  49. opinions and the evolving nature of the beast.
  50.  
  51.  
  52. Tool conformance tips
  53. ---------------------
  54. Do not perform any internal magic in response to messages.  For instance, don't 
  55. automatically CMAbort a CMOpen just because the application sends another CMOpen 
  56. immediately after the first one.  Instead treat the second CMOpen appropriately
  57. by either ignoring it or stacking it depending on the capabilities of your tool. 
  58. You can take other actions within a message however, like receiving a cmWriteMsg
  59. and compressing the data before sending it -- just make sure you respond like
  60. the descriptions in the IM CommToolbox document. 
  61.  
  62. Make it work with MacTerminal v3.0 or something like it.  This should help prove 
  63. conformance to the API. 
  64.  
  65. Add the new caps, faps, or taps resource describing the capabilities of your tool. 
  66.  
  67. Use internal status for asynchronous operations that could be stacked and return 
  68. an error code as the maximum for your queue is reached. 
  69.  
  70.  
  71.  
  72. -------------------------------------------------------------------------------------
  73. DISCLAIMER - This paper contains hints to assist CommToolbox software developers with 
  74. their efforts at producing awesome products.  They are just hints (a form of help) 
  75. however, and are not intended to represent the only possible solution.  
  76.  
  77. It should also be noted that this paper describes current CommToolbox interface 
  78. usage and while the CTB interface could change, upwards-compatibility will remain a 
  79. focus of the CTB production team wherever possible.  Therefore the hints contained 
  80. in this document that use the changing CTB interface represent a solution that should
  81. remain viable.
  82.                         -------------------------------------
  83.                           Copyright © 1992 Apple Computer, Inc.
  84.                           All rights reserved.
  85.